<!DOCTYPE html>
<!--
    Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.
--><html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no, width=device-width">
<meta name="generator" content="joDoc">
<title>Apache Cordova API Documentation</title>
<link rel="stylesheet" type="text/css" href="index.css">
<link rel="stylesheet" type="text/css" href="mobile.css" media="only screen and (max-device-width: 1024px)">
<link rel="stylesheet" type="text/css" href="prettify/prettify.css">
</head>
<body>
        <div id="header">
            <h1><a href="index.html">Apache <strong>Cordova</strong> Documentation</a></h1>
            <small>
                <select><optgroup label="English" value="en">
<option value="edge">edge</option>
<option value="2.2.0rc2">2.2.0rc2</option>
<option value="2.2.0rc1">2.2.0rc1</option>
<option selected value="2.2.0">2.2.0</option>
<option value="2.1.0rc2">2.1.0rc2</option>
<option value="2.1.0rc1">2.1.0rc1</option>
<option value="2.1.0">2.1.0</option>
<option value="2.0.0rc1">2.0.0rc1</option>
<option value="2.0.0">2.0.0</option>
<option value="1.9.0rc1">1.9.0rc1</option>
<option value="1.9.0">1.9.0</option>
<option value="1.8.1">1.8.1</option>
<option value="1.8.0rc1">1.8.0rc1</option>
<option value="1.8.0">1.8.0</option>
<option value="1.7.0rc1">1.7.0rc1</option>
<option value="1.7.0">1.7.0</option>
<option value="1.6.1">1.6.1</option>
<option value="1.6.0rc1">1.6.0rc1</option>
<option value="1.6.0">1.6.0</option>
<option value="1.5.0rc1">1.5.0rc1</option>
<option value="1.5.0">1.5.0</option>
<option value="1.4.1">1.4.1</option>
<option value="1.4.0rc1">1.4.0rc1</option>
<option value="1.4.0">1.4.0</option>
<option value="1.3.0">1.3.0</option>
<option value="1.2.0">1.2.0</option>
<option value="1.1.0">1.1.0</option>
<option value="1.0.0rc3">1.0.0rc3</option>
<option value="1.0.0rc2">1.0.0rc2</option>
<option value="1.0.0rc1">1.0.0rc1</option>
<option value="1.0.0">1.0.0</option>
<option value="0.9.6">0.9.6</option>
<option value="0.9.5.1">0.9.5.1</option>
<option value="0.9.5">0.9.5</option>
<option value="0.9.4">0.9.4</option>
<option value="0.9.3">0.9.3</option>
<option value="0.9.2">0.9.2</option>
</optgroup>
<optgroup label="Español" value="es"><option value="1.0.0">1.0.0</option></optgroup>
<optgroup label="Français" value="fr">
<option value="1.3.0">1.3.0</option>
<option value="1.2.0">1.2.0</option>
<option value="1.1.0">1.1.0</option>
</optgroup>
<optgroup label="Japanese" value="jp">
<option value="2.0.0">2.0.0</option>
<option value="1.9.0">1.9.0</option>
<option value="1.8.1">1.8.1</option>
<option value="1.7.0">1.7.0</option>
<option value="0.9.5">0.9.5</option>
</optgroup>
<optgroup label="Korean" value="kr"><option value="2.0.0">2.0.0</option></optgroup></select></small>
        </div>
        <div id="subheader">
            <h1>Developing a Plugin on Windows Phone</h1>
            <small><select><option value="Developing%2520a%2520Plugin%2520on%2520Windows%2520Phone">Developing a Plugin on Windows Phone</option>
<option value="Developing%20a%20Plugin%20on%20Windows%20Phone_namespaces">      - Namespaces</option>
<option value="Developing%20a%20Plugin%20on%20Windows%20Phone_interpretting_your_arguments_in_c">      - Interpretting your arguments in C#</option>
<option value="Developing%20a%20Plugin%20on%20Windows%20Phone_passing_results_from_c_to_js">      - Passing results from C# to JS</option>
<option value="Developing%20a%20Plugin%20on%20Windows%20Phone_handling_serialization_errors_in_your_plugin_s_c_method">      - Handling serialization errors in your plugin's C# method</option>
<option value="Developing%20a%20Plugin%20on%20Windows%20Phone_advanced_plugin_functionality">      - Advanced Plugin Functionality</option>
<option value="Developing%20a%20Plugin%20on%20Windows%20Phone_common_pitfalls">      - Common Pitfalls</option></select></small>
        </div>

        <div id="sidebar">
            <div class="vertical_divider"></div>
        <h1>API Reference</h1>
<ul>
<li><a href="cordova_accelerometer_accelerometer.md.html#Accelerometer">Accelerometer</a></li>
<li><a href="cordova_camera_camera.md.html#Camera">Camera</a></li>
<li><a href="cordova_media_capture_capture.md.html#Capture">Capture</a></li>
<li><a href="cordova_compass_compass.md.html#Compass">Compass</a></li>
<li><a href="cordova_connection_connection.md.html#Connection">Connection</a></li>
<li><a href="cordova_contacts_contacts.md.html#Contacts">Contacts</a></li>
<li><a href="cordova_device_device.md.html#Device">Device</a></li>
<li><a href="cordova_events_events.md.html#Events">Events</a></li>
<li><a href="cordova_file_file.md.html#File">File</a></li>
<li><a href="cordova_geolocation_geolocation.md.html#Geolocation">Geolocation</a></li>
<li><a href="cordova_globalization_globalization.md.html#Globalization">Globalization</a></li>
<li><a href="cordova_media_media.md.html#Media">Media</a></li>
<li><a href="cordova_notification_notification.md.html#Notification">Notification</a></li>
<li><a href="cordova_splashscreen_splashscreen.md.html#Splashscreen">Splashscreen</a></li>
<li><a href="cordova_storage_storage.md.html#Storage">Storage</a></li>
</ul>
<h1>Guides</h1>
<ul>
<li><a href="guide_getting-started_index.md.html#Getting%20Started%20Guides">Getting Started Guides</a></li>
<li><a href="guide_command-line_index.md.html#Command-Line%20Usage">Command-Line Usage</a></li>
<li><a href="guide_upgrading_index.md.html#Upgrading%20Guides">Upgrading Guides</a></li>
<li><a href="guide_project-settings_index.md.html#Project%20Settings">Project Settings</a></li>
<li><a href="guide_plugin-development_index.md.html#Plugin%20Development%20Guide">Plugin Development Guide</a></li>
<li><a href="guide_whitelist_index.md.html#Domain%20Whitelist%20Guide">Domain Whitelist Guide</a></li>
<li><a href="guide_cordova-webview_index.md.html#Embedding%20WebView">Embedding WebView</a></li>
<li><a href="_index.html">Keyword Index</a></li>
</ul>
</div>

        <div id="scrollable">
            <div id="content">
                <h1><a name="Developing%20a%20Plugin%20on%20Windows%20Phone">Developing a Plugin on Windows Phone</a></h1>

<p>Writing a plugin for Cordova on Windows Phone requires a basic understanding of
the architecture of Cordova. Cordova-WP7 consists of a WebBrowser which hosts the
application javascript code and manages native API calls. There is a BaseCommand
(<code>WP7CordovaClassLib.Cordova.Commands.BaseCommand</code>) class in C# which you can extend,
and it comes with the majority of the 'plumbing' built for you already.</p>

<ol>
<li>Select your project, and right click choose 'Add -&gt; New Item ...'
<ul>
<li>Preferably add it to the 'Plugins' folder, but it is up to you</li>
</ul>
</li>
<li>Select 'Class' and name it <code>Echo.cs</code>
<ul>
<li>The name of this class must EXACTLY match what you call into <code>cordova.exec(win, fail, "Echo", ...)</code>
</li>
</ul>
</li>
<li>
<p>Include the base classes implementation</p>

<pre class="prettyprint"><code>using WP7CordovaClassLib.Cordova;
using WP7CordovaClassLib.Cordova.Commands;
using WP7CordovaClassLib.Cordova.JSON;
</code></pre>
</li>
<li>
<p>Extend your class from BaseCommand</p>

<pre class="prettyprint"><code>public class Echo : BaseCommand
{
    // ...
}
</code></pre>
</li>
<li>
<p>Add a method that is callable from JS</p>

<pre class="prettyprint"><code>public class Echo : BaseCommand
{
    public void echo(string options)
    {
        // all JS callable plugin methods MUST have this signature!
        // public, returning void, 1 argument that is a string
    }
}
</code></pre>
</li>
</ol>
<h2>
<a name="Developing%20a%20Plugin%20on%20Windows%20Phone_namespaces">Namespaces</a>
</h2>

<p>The default namespace for unqualified commands is:</p>

<pre class="prettyprint"><code>namespace Cordova.Extension.Commands
{
    // ...
}
</code></pre>

<p>If you would like to use your own namespace, you will need to make a fully qualified
call to <code>cordova.exec</code>. For example, if you wanted to define your C# class like this:</p>

<pre class="prettyprint"><code>namespace com.mydomain.cordovaExtensions
{
    public class Echo : BaseCommand
    {
        // ...
    }
}
</code></pre>

<p>Then, in JS you would need to call exec like this:</p>

<pre class="prettyprint"><code>codova.exec(win, fail, "com.mydomain.cordovaExtensions.Echo", ...);
</code></pre>

<h2>
<a name="Developing%20a%20Plugin%20on%20Windows%20Phone_interpretting_your_arguments_in_c">Interpretting your arguments in C#</a>
</h2>

<p>The data received by your plugin method is a string value, but in actuallality
looking at our JavaScript code, we see our intention was to pass an array of strings.
Looking back at our JS call to <code>cordova.exec</code>, we see we passed <code>[str]</code>:</p>

<pre class="prettyprint"><code>cordova.exec(win, fail, "Echo", "echo", ["input string"]);
</code></pre>

<p>If we inspect the options string passed in to our <code>Echo.echo</code> method, we will
see that the value is actually:</p>

<pre class="prettyprint"><code>"[\"input string\"]"
</code></pre>

<p>All javascript exec arguments are JSON encoded before being passed into C#.</p>

<p>If we want to treat this as the string we were expecting, we need to decode it.
We can use simple JSON deserialization.</p>

<pre class="prettyprint"><code>string optVal = JsonHelper.Deserialize&lt;string[]&gt;(options)[0];
// optVal now has the value of "input string"
</code></pre>

<h2>
<a name="Developing%20a%20Plugin%20on%20Windows%20Phone_passing_results_from_c_to_js">Passing results from C# to JS</a>
</h2>

<p>The base class BaseCommand provides methods for passing data to your JS callback handlers.
To simply signal that the command has succeeded, when no additional result info is needed,
you can can simply call:</p>

<pre class="prettyprint"><code>DispatchCommandResult(); // calls back with an empty plugin result, considered a success callback
</code></pre>

<p>To pass data back, you will need to call a different version of <code>DispatchCommandResult</code>:</p>

<pre class="prettyprint"><code>DispatchCommandResult(new PluginResult(PluginResult.Status.OK, "Everything went as planned, this is a result that is passed to the success handler."));
</code></pre>

<p>To pass structured object data back to JS, it should be encoded as a JSON string:</p>

<pre class="prettyprint"><code>DispatchCommandResult(new PluginResult(PluginResult.Status.OK, "{result:\"super awesome!\"}"));
</code></pre>

<p>If you need to signal that an error has occured, you can call <code>DispatchCommandResult</code> with a <code>PluginResult</code> object:</p>

<pre class="prettyprint"><code>DispatchCommandResult(new PluginResult(PluginResult.Status.ERROR, "Echo signalled an error"));
</code></pre>

<h2>
<a name="Developing%20a%20Plugin%20on%20Windows%20Phone_handling_serialization_errors_in_your_plugin_s_c_method">Handling serialization errors in your plugin's C# method</a>
</h2>

<p>When interpretting your arguments, it is a good idea to use a try/catch block
in case we have bad input. This is a pattern used throughout the Cordova C# code:</p>

<pre class="prettyprint"><code>string optVal = null;

try 
{
    optVal = JsonHelper.Deserialize&lt;string[]&gt;(options)[0];
}
catch(Exception)
{
    // simply catch the exception, we will handle null values and exceptions together
}

if (optVal == null)
{
    DispatchCommandResult(new PluginResult(PluginResult.Status.JSON_EXCEPTION));
}
else
{
    // ... continue on to do our work
}
</code></pre>

<h2>
<a name="Developing%20a%20Plugin%20on%20Windows%20Phone_advanced_plugin_functionality">Advanced Plugin Functionality</a>
</h2>

<p>See other methods that you can override in:</p>

<ol>
<li><a class="external" href="https://github.com/apache/incubator-cordova-wp7/blob/master/templates/standalone/cordovalib/Commands/BaseCommand.cs">BaseCommand.cs</a></li>
</ol>
<p>For example, you can hook into the '<a href="cordova_events_events.md.html#pause">pause</a>' and '<a href="cordova_events_events.md.html#resume">resume</a>' application events.</p>

<h3>Debugging Plugins</h3>

<p>To debug the C# side, you can use Visual Studio's debugger, just set a break point
at any of the methods exposed by your class.</p>

<p>Javascript is a little more difficult to debug on Windows Phone, you will need to
use <code>console.log</code> to output the state of your plugin, or inform yourself of errors.</p>

<h2>
<a name="Developing%20a%20Plugin%20on%20Windows%20Phone_common_pitfalls">Common Pitfalls</a>
</h2>

<ul>
<li>
<p>Be careful when deciding on the arguments you pass to native in your JavaScript
implementation. Most device platforms expect the args passed to cordova.exec
to be an array, but if you have different types of objects in this array, it
becomes difficult or impossible to deserialize.</p>

<pre class="prettyprint"><code>cordova.exec(win, fail, "ServiceName", "MethodName", ["this is a string", 54, {literal:'trouble'}]);
</code></pre>

<ul>
<li>
<p>This will mean that your C# code will receive a difficult to decode string value, such as:</p>

<pre class="prettyprint"><code>"[\"this is a string\", 54, { literal:'trouble' }]"
</code></pre>
</li>
<li>
<p>Consider converting ALL parameters to strings before calling exec:</p>

<pre class="prettyprint"><code>cordova.exec(win, fail, "ServiceName", "MethodName", ["this is a string", "54", "{literal:'trouble'}"]) ;


string[] optValues = JsonHelper.Deserialize&lt;string[]&gt;(options);
</code></pre>
</li>
</ul>
</li>
<li><p>It is usually a good idea to do parameter checking in your JavaScript code,
before you call exec.  This will let you re-use more JS code between different
native implementations of your plugin.</p></li>
</ul>
</div>
        </div>

        <!-- Functionality and Syntax Highlighting -->
        <script type="text/javascript" src="index.js"></script><script type="text/javascript" src="prettify/prettify.js"></script>
</body>
</html>
